package com.yy.yunpan.file.service;

import com.yy.yunpan.file.entity.File;
import org.springframework.data.domain.Page;

import java.util.Map;

/**
 * 文件服务接口
 *
 * @author YY
 * @since 2025-10-01
 */
public interface FileService {

    /**
     * 获取OSS上传签名
     *
     * @param userId     用户ID
     * @param fileName   文件名
     * @param fileSize   文件大小
     * @param contentType 文件类型
     * @param parentId   父目录ID
     * @return 上传签名信息
     */
    Map<String, Object> getUploadSignature(Long userId, String fileName, Long fileSize, String contentType, Long parentId);

    /**
     * 保存文件元数据
     *
     * @param userId   用户ID
     * @param fileName 原始文件名
     * @param fileSize 文件大小
     * @param fileType 文件类型
     * @param ossKey   OSS存储键
     * @param parentId 父目录ID
     * @param md5      文件MD5
     * @return 文件信息
     */
    File saveFileMetadata(Long userId, String fileName, Long fileSize, String fileType, String ossKey, Long parentId, String md5);

    /**
     * 获取文件列表
     *
     * @param userId    用户ID
     * @param parentId  父目录ID
     * @param page      页码
     * @param size      每页大小
     * @param orderBy   排序字段
     * @param orderType 排序类型
     * @return 文件列表
     */
    Page<File> getFileList(Long userId, Long parentId, Integer page, Integer size, String orderBy, String orderType);

    /**
     * 创建文件夹
     *
     * @param userId     用户ID
     * @param folderName 文件夹名称
     * @param parentId   父目录ID
     * @return 文件夹信息
     */
    File createFolder(Long userId, String folderName, Long parentId);

    /**
     * 删除文件（移动到回收站）
     *
     * @param userId 用户ID
     * @param fileId 文件ID
     */
    void deleteFile(Long userId, Long fileId);

    /**
     * 重命名文件
     *
     * @param userId  用户ID
     * @param fileId  文件ID
     * @param newName 新名称
     * @return 更新后的文件信息
     */
    File renameFile(Long userId, Long fileId, String newName);

    /**
     * 移动文件
     *
     * @param userId       用户ID
     * @param fileId       文件ID
     * @param targetParentId 目标父目录ID
     * @return 更新后的文件信息
     */
    File moveFile(Long userId, Long fileId, Long targetParentId);

    /**
     * 获取用户存储使用情况
     *
     * @param userId 用户ID
     * @return 存储使用情况
     */
    Map<String, Object> getStorageInfo(Long userId);

    /**
     * 获取回收站文件列表
     *
     * @param userId    用户ID
     * @param page      页码
     * @param size      每页大小
     * @param orderBy   排序字段
     * @param orderType 排序类型
     * @return 回收站文件列表
     */
    Page<File> getRecycleFileList(Long userId, Integer page, Integer size, String orderBy, String orderType);

    /**
     * 恢复回收站文件
     *
     * @param userId 用户ID
     * @param fileId 文件ID
     * @return 恢复后的文件信息
     */
    File restoreFile(Long userId, Long fileId);

    /**
     * 彻底删除文件
     *
     * @param userId 用户ID
     * @param fileId 文件ID
     */
    void permanentDeleteFile(Long userId, Long fileId);

    /**
     * 清空回收站
     *
     * @param userId 用户ID
     */
    void clearRecycleBin(Long userId);

    /**
     * 生成文件下载临时链接
     *
     * @param userId 用户ID
     * @param fileId 文件ID
     * @return 下载链接信息
     */
    Map<String, Object> generateDownloadUrl(Long userId, Long fileId);

    /**
     * 生成文件预览临时链接
     *
     * @param userId 用户ID
     * @param fileId 文件ID
     * @return 预览链接信息
     */
    Map<String, Object> generatePreviewUrl(Long userId, Long fileId);
}